home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kprocio.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-10-10  |  6.8 KB  |  218 lines
  1. /* This file is part of the KDE libraries
  2.    Copyright (C) 1997 David Sweet <dsweet@kde.org>
  3.  
  4.    This library is free software; you can redistribute it and/or
  5.    modify it under the terms of the GNU Library General Public
  6.    License version 2 as published by the Free Software Foundation.
  7.  
  8.    This library is distributed in the hope that it will be useful,
  9.    but WITHOUT ANY WARRANTY; without even the implied warranty of
  10.    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  11.    Library General Public License for more details.
  12.  
  13.    You should have received a copy of the GNU Library General Public License
  14.    along with this library; see the file COPYING.LIB.  If not, write to
  15.    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  16.    Boston, MA 02110-1301, USA.
  17. */
  18. #ifndef KPROCIO_H_
  19. #define KPROCIO_H_
  20.  
  21. #include <qstring.h>
  22. #include <kprocess.h>
  23. #include <qstrlist.h>
  24. #include "kdelibs_export.h"
  25.  
  26. class KProcIOPrivate;
  27. class QTextCodec;
  28.  
  29. /**
  30.  * KProcIO
  31.  *
  32.  * This class provides a slightly simpler interface to the communication
  33.  *  functions provided by KProcess.  The simplifications are:
  34.  *    @li The buffer for a write is copied to an internal KProcIO
  35.  *        buffer and maintained/freed appropriately.  There is no need
  36.  *        to be concerned with wroteStdin() signals _at_all_.
  37.  *    @li readln() reads a line of data and buffers any leftovers.
  38.  *    @li Conversion from/to unicode.
  39.  *
  40.  * Basically, KProcIO gives you buffered I/O similar to fgets()/fputs().
  41.  *
  42.  * Aside from these, and the fact that start() takes different
  43.  * parameters, use this class just like KProcess.
  44.  *
  45.  * @author David Sweet
  46.  * @short A slightly simpler interface to KProcess
  47.  **/
  48.  
  49.  
  50. class KDECORE_EXPORT KProcIO : public KProcess
  51. {
  52.   Q_OBJECT
  53.  
  54. public:
  55.   /**
  56.    * Constructor
  57.    */
  58.   KProcIO ( QTextCodec *codec = 0 );
  59.  
  60.   /**
  61.    * Destructor
  62.    */
  63.   ~KProcIO();
  64.  
  65.   /**
  66.    * Sets the communication mode to be passed to KProcess::start()
  67.    * by start(). The default communication mode is KProcess::All.
  68.    * You probably want to use this function in conjunction with
  69.    * KProcess::setUsePty().
  70.    * @param comm the communication mode
  71.    */
  72.   void setComm (Communication comm);
  73.  
  74.   /**
  75.    *  Starts the process. It will fail in the following cases:
  76.    *  @li The process is already running.
  77.    *  @li The command line argument list is empty.
  78.    *  @li The starting of the process failed (could not fork).
  79.    *  @li The executable was not found.
  80.    *
  81.    *  @param runmode For a detailed description of the
  82.    *  various run modes, have a look at the
  83.    *  general description of the KProcess class.
  84.    *  @param includeStderr If true, data from both stdout and stderr is
  85.    *  listened to. If false, only stdout is listened to.
  86.    *  @return true on success, false on error.
  87.    **/
  88.   bool start (RunMode  runmode = NotifyOnExit, bool includeStderr = false);
  89.  
  90.   /**
  91.    * Writes text to stdin of the process.
  92.    * @param line Text to write.
  93.    * @param appendnewline if true, a newline '\\n' is appended.
  94.    * @return true if successful, false otherwise
  95.    **/
  96.   bool writeStdin(const QString &line, bool appendnewline=true);
  97.  
  98.   /**
  99.    * Writes text to stdin of the process.
  100.    * @param line Text to write.
  101.    * @param appendnewline if true, a newline '\\n' is appended.
  102.    * @return true if successful, false otherwise
  103.    **/
  104.   bool writeStdin(const QCString &line, bool appendnewline);
  105.  
  106.   /**
  107.    * Writes data to stdin of the process.
  108.    * @param data Data to write.
  109.    * @return true if successful, false otherwise
  110.    **/
  111.   bool writeStdin(const QByteArray &data);
  112.  
  113.   //I like fputs better -- it's the same as writeStdin
  114.   //inline
  115.   /**
  116.    * This function just calls writeStdin().
  117.    *
  118.    * @param line Text to write.
  119.    * @param AppendNewLine if true, a newline '\\n' is appended.
  120.    * @return true if successful, false otherwise
  121.    * @deprecated
  122.    **/
  123.   KDE_DEPRECATED bool fputs (const QString &line, bool AppendNewLine=true)
  124.     { return writeStdin(line, AppendNewLine); }
  125.  
  126.   /**
  127.    * Closes stdin after all data has been send.
  128.    */
  129.   void closeWhenDone();
  130.  
  131.   /**
  132.    * Reads a line of text (up to and including '\\n').
  133.    *
  134.    * Use readln() in response to a readReady() signal.
  135.    * You may use it multiple times if more than one line of data is
  136.    *  available.
  137.    * Be sure to use ackRead() when you have finished processing the
  138.    *  readReady() signal.  This informs KProcIO that you are ready for
  139.    *  another readReady() signal.
  140.    *
  141.    * readln() never blocks.
  142.    *
  143.    * autoAck==true makes these functions call ackRead() for you.
  144.    *
  145.    * @param line is used to store the line that was read.
  146.    * @param autoAck when true, ackRead() is called for you.
  147.    * @param partial when provided the line is returned
  148.    * even if it does not contain a '\\n'. *partial will be set to
  149.    * false if the line contains a '\\n' and false otherwise.
  150.    * @return the number of characters read, or -1 if no data is available.
  151.    **/
  152.   int readln (QString &line, bool autoAck=true, bool *partial=0);
  153.  
  154.   /**
  155.    * This function calls readln().
  156.    * @param line is used to store the line that was read.
  157.    * @param autoAck when true, ackRead() is called for you.
  158.    * @return the number of characters read, or -1 if no data is available.
  159.    * @deprecated use readln. Note that it has an inverted autoAck default,
  160.    *  though.
  161.    **/
  162.   KDE_DEPRECATED int fgets (QString &line, bool autoAck=false)
  163.     { return readln (line, autoAck); }
  164.  
  165.   /**
  166.    * Reset the class.  Doesn't kill the process.
  167.    **/
  168.   void resetAll ();
  169.  
  170.   /**
  171.    * Call this after you have finished processing a readReady()
  172.    * signal.  This call need not be made in the slot that was signalled
  173.    * by readReady().  You won't receive any more readReady() signals
  174.    * until you acknowledge with ackRead().  This prevents your slot
  175.    * from being reentered while you are still processing the current
  176.    * data.  If this doesn't matter, then call ackRead() right away in
  177.    * your readReady()-processing slot.
  178.    **/
  179.   void ackRead ();
  180.  
  181.   /**
  182.    *  Turns readReady() signals on and off.
  183.    *   You can turn this off at will and not worry about losing any data.
  184.    *   (as long as you turn it back on at some point...)
  185.    * @param enable true to turn the signals on, false to turn them off
  186.    */
  187.   void enableReadSignals (bool enable);
  188.  
  189. signals:
  190.   /**
  191.    * Emitted when the process is ready for reading.
  192.    * @param pio the process that emitted the signal
  193.    * @see enableReadSignals()
  194.    */
  195.   void readReady(KProcIO *pio);
  196.  
  197. protected:
  198.   QPtrList<QByteArray> outbuffer;
  199.   QCString recvbuffer;
  200.   QTextCodec *codec;
  201.   int rbi;
  202.   bool needreadsignal, readsignalon, writeready;
  203.  
  204.   void controlledEmission ();
  205.  
  206. protected slots:
  207.   void received (KProcess *proc, char *buffer, int buflen);
  208.   void sent (KProcess *);
  209.  
  210. protected:
  211.   virtual void virtual_hook( int id, void* data );
  212. private:
  213.   KProcIOPrivate *d;
  214. };
  215.  
  216. #endif // KPROCIO_H_
  217.  
  218.